<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: Neon</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__c_p_u__support__c_p_u-_a_r_m-_n_e_o_n.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Neon </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Introduction</h2>
<p>Android NDK r3 added support for the new 'armeabi-v7a' ARM-based ABI that allows native code to use two useful instruction set extensions:</p>
<ul>
<li>Thumb-2, which provides performance comparable to 32-bit ARM instructions with similar compactness to Thumb-1</li>
<li><p class="startli">VFPv3, which provides hardware FPU registers and computations, to boost floating point performance significantly.</p>
<p class="startli">More specifically, by default 'armeabi-v7a' only supports VFPv3-D16 which only uses/requires 16 hardware FPU 64-bit registers.</p>
</li>
</ul>
<p>More information about this can be read in docs/CPU-ARCH-ABIS.html</p>
<p>The ARMv7 Architecture Reference Manual also defines another optional instruction set extension known as "ARM Advanced SIMD", nick-named "NEON". It provides:</p>
<ul>
<li>A set of interesting scalar/vector instructions and registers (the latter are mapped to the same chip area as the FPU ones), comparable to MMX/SSE/3DNow! in the x86 world.</li>
<li>VFPv3-D32 as a requirement (i.e. 32 hardware FPU 64-bit registers, instead of the minimum of 16).</li>
</ul>
<p>Not all ARMv7-based Android devices will support NEON, but those that do may benefit in significant ways from the scalar/vector instructions.</p>
<p>The NDK supports the compilation of modules or even specific source files with support for NEON. What this means is that a specific compiler flag will be used to enable the use of GCC ARM Neon intrinsics and VFPv3-D32 at the same time. The intrinsics are described here:</p>
<p><a href="http://gcc.gnu.org/onlinedocs/gcc/ARM-NEON-Intrinsics.html">http://gcc.gnu.org/onlinedocs/gcc/ARM-NEON-Intrinsics.html</a></p>
<h2><code>Using LOCAL_ARM_NEON</code></h2>
<p>Define LOCAL_ARM_NEON to 'true' in your module definition, and the NDK will build all its source files with NEON support. This can be useful if you want to build a static or shared library that specifically contains NEON code paths.</p>
<h2>Using the <code>.neon</code> suffix:</h2>
<p>When listing sources files in your LOCAL_SRC_FILES variable, you now have the option of using the .neon suffix to indicate that you want to corresponding source(s) to be built with Neon support. For example: </p>
<pre class="fragment">    LOCAL_SRC_FILES := foo.c.neon bar.c
</pre><p>Will only build 'foo.c' with NEON support.</p>
<p>Note that the .neon suffix can be used with the .arm suffix too (used to specify the 32-bit ARM instruction set for non-NEON instructions), but must appear after it.</p>
<p>In other words, 'foo.c.arm.neon' works, but 'foo.c.neon.arm' does NOT.</p>
<h2>Build Requirements</h2>
<p>Neon support only works when targeting the 'armeabi-v7a' or 'x86' ABI, otherwise the NDK build scripts will complain and abort. Neon is partially supported on x86 via translation header (To learn more about it, see <a href="./md_3__key__topics__c_p_u__support__c_p_u-_x86.html">x86</a>). It is important to use checks like the following in your Android.mk: </p>
<pre class="fragment">    # define a static library containing our NEON code
    ifeq ($(TARGET_ARCH_ABI),$(filter $(TARGET_ARCH_ABI), armeabi-v7a x86))
        include $(CLEAR_VARS)
        LOCAL_MODULE    := mylib-neon
        LOCAL_SRC_FILES := mylib-neon.c
        LOCAL_ARM_NEON  := true
        include $(BUILD_STATIC_LIBRARY)
    endif # TARGET_ARCH_ABI == armeabi-v7a || x86
</pre><h2>Runtime Detection</h2>
<p>As said previously, NOT ALL ARMv7-BASED ANDROID DEVICES WILL SUPPORT NEON ! It is thus crucial to perform runtime detection to know if the NEON-capable machine code can be run on the target device.</p>
<p>To do that, use the cpufeatures library that comes with this NDK. To learn more about it, see docs/CPU-FEATURES.html.</p>
<p>You should explicitly check that android_getCpuFamily() returns ANDROID_CPU_FAMILY_ARM, and that android_getCpuFeatures() returns a value that has the ANDROID_CPU_ARM_FEATURE_NEON flag set, as in: </p>
<pre class="fragment">      #include &lt;cpu-features.h&gt;

      ...
      ...

      if (android_getCpuFamily() == ANDROID_CPU_FAMILY_ARM &amp;&amp;
          (android_getCpuFeatures() &amp; ANDROID_CPU_ARM_FEATURE_NEON) != 0)
      {
          // use NEON-optimized routines
          ...
      }
      else
      {
          // use non-NEON fallback routines instead
          ...
      }

      ...
</pre><h2>Sample code</h2>
<p>Look at the source code for the "hello-neon" sample in this NDK for an example on how to use the 'cpufeatures' library and Neon intrinsics at the same time.</p>
<p>This implements a tiny benchmark for a FIR filter loop using a C version, and a NEON-optimized one for devices that support it. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
